home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Topik / Topik - Disk 18 - Serious (19xx)(Topik Public Domain)(PD)[WB].zip / Topik - Disk 18 - Serious (19xx)(Topik Public Domain)(PD)[WB].adf / Conman / ConMan.doc < prev    next >
Text File  |  1989-10-01  |  25KB  |  461 lines

  1.                               ConMan V1.3 Revision 2
  2.                    Copyright (c) 1987, 1988 by William S. Hawes
  3.    
  4.    ConMan is a replacement console handler that provides line editing and
  5.    command history for any software that uses CON: windows.  It runs under
  6.    AmigaDOS V1.2 and later, and is completely transparent to other software.
  7.    After ConMan has been activated, all CON: windows opened by AmigaDOS will 
  8.    automatically use the ConMan handler.  This includes the console windows
  9.    opened by NEWCLI as well as any data input/output windows that your other
  10.    software may use.
  11.    
  12.    Features new to ConMan V1.3 include the CND: handler for invisible,
  13.    non-blocking type-ahead, the CNX: (extensible) handler for use of the
  14.    serial device as a console, improved editing of long lines, and support
  15.    for superbitmap windows.
  16.    
  17.    As was the case with prior releases, ConMan is distributed as shareware
  18.    (user-supported software), and I'm pleased to report that the rate of
  19.    contributions has increased since that last release.  Shareware is a
  20.    welcome alternative to the high costs of commercial software, and I hope
  21.    that you'll do your part to support ConMan and other shareware products.
  22.    
  23.    
  24.                           ----- Line Editing -----
  25.    ConMan allows you to edit the active (command) line using the left- and
  26.    right-arrow keys for cursor positioning.  The shifted left-arrow key 
  27.    skips to the beginning of the current or previous word, and the shifted 
  28.    right-arrow key skips to the start of the next word.
  29.    
  30.    ConMan supports both insert and overstrike editing modes.  The CTRL-A key
  31.    toggles between the two modes, and the CTRL-^ key unconditionally selects
  32.    insert mode.  The default input mode is insert, but you can set the global
  33.    -o flag to select overstrike mode.  The input mode normally reverts to the
  34.    default mode each time you press RETURN, but the global -s ("sticky") flag
  35.    will cause the mode to remain set until you change it explicitly.
  36.    
  37.    You can select insert or overstrike mode when you first install ConMan,
  38.    and can change it at any time using the SetCMan command utility.  Try 
  39.    experimenting to see which input mode you like best, but note that the
  40.    input modes are global and therefore apply to ALL ConMan windows.  Refer
  41.    to the paragraph on installation for a list of the global option flags.
  42.    
  43.    There are several keys that can be used to delete characters, words, or 
  44.    the entire line.  The DEL key deletes the character under the cursor, 
  45.    and the BACKSPACE key deletes the character to the left of the cursor.  
  46.    CTRL-Y deletes from the cursor position to the end of the line, and 
  47.    CTRL-U deletes from the cursor to the start of the line.  CTRL-X deletes
  48.    the entire line, in keeping with the default CON: device.
  49.     
  50.    Function keys F7 and F8 can be used to delete words in the backwards and 
  51.    forwards direction, respectively.  They work just like the shifted left- 
  52.    and right-arrow keys except that the characters are deleted.
  53.    
  54.    CTRL-Z deletes both the current line and any lines that have been typed
  55.    ahead (but not yet read); this is very handy if you want to completely 
  56.    abandon all typed-ahead lines.  CTRL-R provides a less drastic recall 
  57.    by posting the typed-ahead lines back to the command line.  CTRL-W clears
  58.    the entire window and then redisplays the active line.
  59.    
  60.    The Undo Buffer.
  61.    Suppose that you're editing a line and you accidentally hit the up- or
  62.    down-arrow key.  You've just lost the line, right?  Not at all --- just
  63.    press the CTRL-- (control-minus) key and the former line will be posted
  64.    back to the command line, with the cursor right where you left it!
  65.    
  66.    There is no limit to the number of lines that can be undone, but only
  67.    lines that have been changed are added to the undo buffer.  All "undo"
  68.    lines are discarded when you finally enter RETURN.
  69.    
  70.    Flow Control.
  71.    CTRL-S and CTRL-Q have been implemented to hold and release the screen
  72.    output, respectively.  After pressing the CTRL-S key, all output to the
  73.    window will be held until you release it with a CTRL-Q.  ConMan will now
  74.    (as of revision 2) "beep" the display if you try to type with CTRL-S in
  75.    effect, in order to provide some visual indication that output is held.
  76.    
  77.    End-of-File.
  78.    ConMan recognizes the CTRL-\ character as an end-of-file and sends a
  79.    zero-length block to the task reading from the handler.  CTRL-\ can be
  80.    used to terminate a copy operation.
  81.    
  82.    All characters not explicitly required for editing purposes are passed on
  83.    to the command line.  In order to provide a consistent display, characters
  84.    that might cause interference with the display (like CTRL-L) are rendered
  85.    as a caret (^) followed by the uppercase alphabetic character.  The CTRL-N
  86.    (shift-in) and CTRL-O (shift-out) characters are supported by ConMan;
  87.    these are non-printable by themselves, but serve to select and unselect
  88.    the alternate character set.  Miscellaneous non-printable characters are
  89.    displayed as a hash mark.
  90.    
  91.    ConMan now allows control sequences can be entered incrementally.  For
  92.    example, entering ESC, [, 0, and ~ will simulate the effect of an F1 key.
  93.    
  94.    
  95.                           ----- Command History -----
  96.    ConMan "remembers" the commands that you type and lets you recall them
  97.    sequentially using the up- and down-arrow keys.  If you go past the line
  98.    you want, the down-arrow key will retrieve the next (more recent) line.  
  99.    The shifted up-arrow key recalls the oldest line, and shifted down-arrow 
  100.    recalls the most recent line.  The CTRL-B key clears the history buffer.
  101.    
  102.    The history buffer is organized as a fixed-length memory pool with a
  103.    default length of 488 bytes.  New lines are inserted at one end, and 
  104.    the oldest lines are "pushed off" the other end to make room.  The number
  105.    of lines that can be saved depends on their lengths, but is generally in
  106.    the range of 25 to 30.  The default size can be changed when you install 
  107.    ConMan by using the -b option followed by the desired size in bytes.  
  108.    For example, the command "conman -c -b1000" installs ConMan with a 
  109.    1000-byte history buffer.
  110.    
  111.    ConMan maintains the history in one of two modes.  In the default mode, 
  112.    recalled lines are not reentered into the history buffer unless the line
  113.    was "touched," and the history index pointer is left positioned at the
  114.    retrieved line.  This mode is convenient if you often go back into the
  115.    buffer to retrieve sequences of commands.
  116.    
  117.    In "true history" mode, every line is reentered into the history buffer,
  118.    even if it wasn't modified after being recalled.  The history pointer is
  119.    always reset (to the most recent line) whenever a line is added to the
  120.    buffer.
  121.    
  122.    The history mode can be selected when ConMan is installed or by using the
  123.    SetCMan utility.  Note that ConMan now checks for duplicate entries
  124.    irrespective of whether standard or "true" history is selected.  If the
  125.    current line matches the previous line entered, the line is not reentered.
  126.    
  127.    Minimum Line Length.
  128.    You can define a minimum line length to be saved in the history buffer by
  129.    using the -LNNN option.  The number following the -L is the limit at or
  130.    below which lines will not be saved; the default value is 0.  For example,
  131.    "conman -c -L2" will ignore lines of 2 or fewer characters.
  132.    
  133.    Wrap-Around History.
  134.    If you prefer to maintain the command history as a circular buffer rather 
  135.    than as a stack, try setting the -wrap option with ConMan or SetCMan.  
  136.    The index will "wrap-around" when it hits the top or bottom of the stack.
  137.    
  138.    Versions 1.1 and later of ConMan include a command called "History" to
  139.    save, load, or display the history buffer.  Refer to the "history.doc" 
  140.    file for more information.
  141.    
  142.    
  143.                           ----- Function Keys -----
  144.    ConMan has several additional editing functions and window control options
  145.    that use the function keys.
  146.    
  147.    Key F1 shrinks ("iconifies") the window to its minimum size, and key F2 
  148.    "zooms" the window to its maximum size (usually the entire screen.)  Both
  149.    keys act as toggles, and shrunken windows may be zoomed (and vice-versa.)
  150.    ConMan V1.3 provides a minor enhancement to the zoom feature:  if the 
  151.    window is not exactly at the top of the screen when F2 is hit, it will be
  152.    positioned one pixel down from the top, rather than right at the top.  
  153.    This allows you to slide the screen even if the window covers most of it.
  154.    If the window was opened without a sizing gadget, neither F1 or F2 will 
  155.    have any effect.
  156.    
  157.    Keys F5 and F6 are used to search for commands.  If you type a partial 
  158.    command line and then press F6, ConMan searches in the up-arrow direction 
  159.    for a line matching up to the cursor position.  You can move the cursor
  160.    to the right to constrain the search.  Key F5 works similarly in the 
  161.    down-arrow direction.
  162.    
  163.    Keys F7 and F8 delete words in the backwards and forwards direction.  
  164.    They operate just like the shifted left- and right-arrow keys except that
  165.    the words are deleted rather than just skipped over.
  166.    
  167.    Function key F9 moves the screen to the front or back of the display, 
  168.    and F10 moves the window to the front or back.  Both keys act as toggles 
  169.    provided that you don't deactivate the window or screen.  These keys are
  170.    useful when you're working with multiple windows or screens and need to 
  171.    peek at the one in back.
  172.    
  173.    
  174.                         ----- Window Definitions -----
  175.    ConMan accepts the standard AmigaDOS window specifications.  For example,
  176.    "CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size,
  177.    beginning in position (160,50).  The numeric parameters are truncated
  178.    against the maximum screen size, so a larger-than-normal window may be
  179.    safely specified (for those of you using "morerows").  The default size
  180.    is the full screen width and height.  ConMan sets the minimum window size
  181.    to allow room for the close gadget and depth gadgets.
  182.    
  183.    Various Intuition options and gadgets can be selected by including a list
  184.    of attributes after the window title.  Here's how it works:  put another 
  185.    slash ("/") after the window title, and follow it with any of the
  186.    attribute options listed below.
  187.    
  188.       Option Character                 Default Value   
  189.       ----------------                 -------------
  190.       A <==> Activate                  Activated
  191.       B <==> BackDrop                  Not a backdrop
  192.       C <==> Close gadget              No close gadget
  193.       D <==> Depth gadgets             Depth gadgets
  194.       M <==> Move (drag) gadget        Drag gadget
  195.       N <==> NoBorder                  Border (sorry, "B" was used)
  196.       R <==> Refresh (SMART/SIMPLE)    Smart refresh
  197.       S <==> Sizing gadget             Sizing gadget
  198.       Z <==> Zero-Zero                 Not a GZZ
  199.    
  200.    Each option character will TOGGLE the corresponding window attribute,
  201.    so if you include an option twice, it will cancel the effect.  Any 
  202.    unrecognized attribute characters are ignored, and the closing slash is 
  203.    optional.  My apologies to those who wanted a slash in the title.
  204.    
  205.    Examples: CON:10/10/300/100/Behind/nb/   a borderless backdrop window.
  206.              CON:10/10/300/100/Fixed/acm    a nonactivated window, with a 
  207.                                             close gadget, that won't budge.
  208.    
  209.    You can select the colors for the window's titlebar area by appending a
  210.    '/' to the attribute list and specifying the "detail pen" and "block pen"
  211.    color values; the color numbers are listed below.
  212.  
  213.       Pen Number  Color
  214.       ----------  -----
  215.           0       Blue
  216.           1       White
  217.           2       Black
  218.           3       Red
  219.  
  220.    For example, "CON://640/100/Colors!/ac/23" would specify a window with
  221.    black letters (the detail pen) on a red titlebar (the block pen).
  222.  
  223.  
  224.                           ----- Installation ----
  225.    To install ConMan you'll need to copy a few files to your system disk,
  226.    but don't worry --- they're all small.  Install the file "Conhandler"
  227.    (184 bytes) in your L: directory, to keep those bigger handlers company.  
  228.    Then copy the file "conhandler.library" (6612 bytes) into your LIBS:
  229.    directory.  Now copy the commands "ConMan", "SetCMan", and "History" to
  230.    your C: directory; the other command programs are optional.  The included
  231.    "ExecuteMe" file will handle the installation for you if you'd rather do
  232.    it automatically.
  233.    
  234.    If you received ConMan in the form of an ARCed file, first deARC it and
  235.    then rename "conlib.lib" to "conhandler.library", or use the provided
  236.    "ARCInstall" script to copy the files.
  237.    
  238.    Once these files have been installed, issue the command "conman -c" to 
  239.    activate the handler.  After you've activated ConMan, open a CLI window
  240.    using NEWCLI and check to make sure that the new window has line editing
  241.    and command history.  Once everything is working properly, you should
  242.    place the "conman -c" command in your startup-sequence so that it's always
  243.    available.
  244.    
  245.    NOTE:  ConMan affects only those windows opened AFTER you activate it!
  246.    It would be very impolite indeed to pull the old handler out from under 
  247.    the existing console windows.
  248.    
  249.    You can specify several command line arguments with the ConMan command:
  250.    
  251.       Code     Action
  252.       ------   ------
  253.       -bNNNN   select buffer size NNNN bytes
  254.       -c       install as CON: (the default)
  255.       -d       disable control-C break on write
  256.       -lNNN    minimum length to save
  257.       -o       select overstrike mode
  258.       -r       install as RAW:
  259.       -s       select "sticky" mode
  260.       -t       maintain "true history"
  261.       -w       select "wrap-around" history
  262.    
  263.    These command options can appear in any order and remain in effect until
  264.    you reboot the computer.  The -q option used in previous releases is now
  265.    obsolete, as ConMan writes its copyright to standard output by default.
  266.    
  267.    A separate utility program called "SetCMan" has been provided to modify 
  268.    or display the global options.  You can use SetCMan to change the -o, 
  269.    -s, -t, or -w options at any time.
  270.    Examples: setcman ?
  271.              setcman -o -s -t
  272.    
  273.    If you usually operate from WorkBench and only occasionally need a CLI,
  274.    you can activate ConMan by using the icons.  First double-click on the 
  275.    "LoadLib" icon to load the conhandler library, and then activate ConMan
  276.    by double-clicking the "ConMan" icon.  The next CLI you open should now
  277.    have the line editing and command history provided by ConMan.
  278.    
  279.    
  280.                           ----- Distribution -----
  281.    This program is distributed as shareware (user-supported software) to 
  282.    Amigoid life-forms everywhere!  Make sure your friends get a copy.  
  283.    Your contributions are greatly appreciated and will help me maintain 
  284.    ConMan as well as develop new products.  Send all correspondence to:
  285.    
  286.          By Mail:                      By Telephone or EMail:
  287.          -----------------             ------------------------------
  288.          William S. Hawes              Phone: (508) 568-8695
  289.          P.O. Box 308                  BIX: whawes
  290.          Maynard, MA 01754             CIS: 72230,267
  291.          USA                           PLINK: whawes
  292.                                        USENET: hawes@dino.ulowell.edu
  293.  
  294.    The suggested contribution is $10 (based on an earlier survey), but any 
  295.    amount is welcome.  The number of registered ConMan users has increased
  296.    significantly since the last release, but is still far below what would
  297.    be expected for a comparable commercial product.
  298.    
  299.    Commercial vendors are welcome to include ConMan with their products,
  300.    provided that it's noted as being shareware and that the documentation 
  301.    accompanies the software.
  302.    
  303.    
  304.                           ----- Other Products -----
  305.    I have a couple of other products available commercially.   ARexx and 
  306.    WShell can be found at better dealers**, or you can order them directly 
  307.    from me at the above address.
  308.    
  309.    ARexx is a multitasking implementation of the REXX language, a high-level
  310.    interpreted language designed for macro-processing.  ARexx has become the
  311.    de facto standard for inter-program communications and can be used as the
  312.    macro language for any software package that includes an ARexx interface.
  313.    It's both powerful and easy-to-learn, and is well documented in a 150-page
  314.    manual.  ................................. Only $49.95 (plus $2 shipping)
  315.    
  316.    WShell is a much-enhanced but highly compatible CLI replacement that
  317.    offers aliases, built-in and resident commands, concurrent command piping
  318.    (as in pgm1 | pgm2 | ... | pgmN), extended prompt/window titlebar fields,
  319.    transparent support for REXX macro programs, an "implicit" CD command,
  320.    script-bit support, and lots of other features.  Isn't it time you put
  321.    some mussel into your command environment?  Just 50 clams (+ $2 shipping)
  322.    
  323.    ** better dealers are those that stock ARexx and WShell.
  324.    
  325.    
  326.                           ----- Further Notes -----
  327.    ConMan also accepts window specifications in the form "CON:w20480", where
  328.    the hex digits following the "w" are the absolute address of an Intuition
  329.    window pointer.  This allows you to attach a console handler to a window
  330.    in a multitasking-safe way (unlike the methods that require setting a
  331.    field in the DOS device list).  If you're writing in C, you could use
  332.    the following sequence to open a window and attach a DOS console to it:
  333.    
  334.          window = OpenWindow(&newwindow);   /* get a window          */
  335.          sprintf(buffer,"CON:W%x",window);  /* build the name string */
  336.          file  = Open(buffer,MODE_OLDFILE); /* open a console stream */ 
  337.    
  338.    You can open a console window on a custom screen by passing the hex
  339.    address of the screen preceded by an "S" in the specification string,
  340.    as in "CON:S123abc/10/10/300/100/MyWindow."  ConMan will accept "S*" as
  341.    a shorthand notation for the frontmost screen, so a specification like
  342.    "CON:S*/0/0/300/100/Front" would open on whichever screen was in front.
  343.    
  344.    In addition, ConMan now supports superbitmap windows as well.  The bitmap
  345.    structure is passed as a "B" followed by the hex address, as for example
  346.    "CON:B123ABC/0/0/300/100/Super!".  The console device currently has some
  347.    bugs related to using superbitmaps (for example, the cursor disappears),
  348.    but this feature may be handy anyway.
  349.    
  350.    
  351.    Other Names.
  352.    ConMan is actually several DOS handlers rolled into one, and it selects
  353.    the desired mode of operation by looking at the name used to open it.  
  354.    The four special names recognized are CND:, CNX:, PIP:, and RAW:, and all
  355.    other names are considered equivalent to CON:.
  356.    
  357.    In order to use ConMan under any name other than CON:, you'll need to add
  358.    one or more of the supplied mountlist entries to your DEVS:mountlist file
  359.    and then issue the "mount" command.  For example, to define ConMan as the
  360.    CNC: device, add the CNC: entry to DEVS:mountlist and issue "mount CNC:".
  361.    Once you've done this, you can get a ConMan window by specifying a name
  362.    like CNC://640/100/MyWindow.  This allows the CON: definition to be left
  363.    intact, in case there are any incompatibilities between ConMan and your
  364.    existing software (but please let me know of any problems!)
  365.  
  366.    Warning: DO NOT USE the ARP mount command to mount ConMan --- it has a
  367.    known bug that causes the console handler to open up in RAW mode.
  368.    
  369.    The CND: handler, new to V1.3, operates in a mode that allows invisible
  370.    (non-blocking) type-ahead.  After the line you enter has been read, any
  371.    further input is not displayed until the command shell (or other software)
  372.    again reads from the console.  This gives unimpeded access to whatever 
  373.    software is writing to the console.  
  374.    Example:  NewCLI "CND://640/100/VAX Head!"
  375.    
  376.    The CNX: handler is also new to V1.3, and provides extensibility by
  377.    allowing you to specify any EXEC-level device for the console display.
  378.    The display device name and unit are passed immediately following the
  379.    handler name, as in "CNX:device-name/unit".  For example, you could
  380.    specify the serial device as "CNX:serial.device/0", providing an AUX:
  381.    handler with full line editing and command history.  The display device
  382.    must support the standard ANSI control sequences on read and write.
  383.    Example:  NewCLI CNX:serial.device/0
  384.    
  385.    ConMan is also a pipe-handler responding to the name PIP:NNNN, where
  386.    NNNN is the "capacity" of the pipe.  It must be opened using a private
  387.    packet called ACTION_DOUBLE (value 2000L), and the filehandle you get
  388.    from a call to Open("PIP:",2000) counts for two and so can be cloned
  389.    by your program.  After allocating a filehandle structure (using the
  390.    AmigaDOS memory conventions), just copy the filehandle from Open()
  391.    into the new structure --- and don't forget to Close() both of them!
  392.    My WShell command shell uses the ConMan PIP: device as its pipe handler.
  393.    
  394.    Those of you with AmigaDOS 1.3 (but not yet blessed with WShell) will
  395.    appreciate the sly inclusion of the NEWCON: mountlist entry.
  396.  
  397.    
  398.    Break Signals.
  399.    Break signals are generated by typing a control-C, D, E, or F and can be
  400.    delivered to any task that has opened, read from, or written to ConMan.
  401.    The break-signal handling in ConMan is much more sophisticated than that
  402.    in the standard CON: handler, and additional improvements have been made
  403.    in V1.3 to eliminate the possibility of signalling a non-existent task.
  404.    ConMan is able to signal a task that has only read from or written to the
  405.    console -- even if it hasn't opened it -- by holding the break event until
  406.    a read or write request arrives.
  407.    
  408.    In addition to the break signals generated by user input, ConMan will
  409.    send a control-C break to any task that continues to write to the handler
  410.    when it's trying to close.  ConMan is in such a "closing" state after the
  411.    close gadget on a window has been hit, or if it is a PIP: pipe with only
  412.    one open remaining.  This automatic "break-on-write" provides a way of
  413.    propagating a signal back through a series of piped programs.  Auto-break
  414.    can be disabled by specifying the -disable option to the ConMan command.
  415.  
  416.    
  417.    Keymapping.
  418.    ConMan supports the Amiga's keymapping facility, which allows you to 
  419.    reassign the editing functions to the keys of your choice.  To do this, 
  420.    you must first construct a keymap either in assembly language or with
  421.    the help of a keymap editor.  You can then load the keymap using the 
  422.    SetMap program on your WorkBench disk.  By default SetMap makes a keymap 
  423.    global; if you want to use a special keymap from just one CLI, you can 
  424.    use the included KeyMap command to define the desired map.  KeyMap with 
  425.    no arguments will display a list of the available keymaps.
  426.    
  427.    
  428.                            ----- What Next? -----
  429.    Most of the requested features have been added to ConMan now, but there
  430.    are a still a couple of suggestions being considered.  Several users have
  431.    requested more flexible keymapping features to allow function keys to
  432.    be redefined on the fly.  Another possibility is an improved "iconify"
  433.    state, so that the window can be double-clicked back to the former size.
  434.    
  435.    
  436.                               ----- Bugs -----
  437.    All known bugs have been fixed in this release, so you should find it to 
  438.    be very reliable.  If you do find a problem, PLEASE report it so I can 
  439.    fix it!!
  440.    
  441.    Previous versions of ConMan (before 1.3) exhibited a problem associated
  442.    with very rapid toggling between the "shrink" and "zoom" window states.
  443.    This problem has been fixed by adding a further level of interlocking,
  444.    and the F1/F2 keys should now be completely safe.  Furthermore, the
  445.    underlying cause of the window-sizing problem will be fixed in version 
  446.    1.4 of Intuition, so there should be no more trouble from this source.
  447.    
  448.    One warning still applies: the console device exhibits serious problems
  449.    with windows below some minimum size.  Opening windows of certain sizes 
  450.    (e.g. con:0/0/10/20/) may cause the machine to crash, whether or not
  451.    ConMan is active.  For these reasons, I strongly urge you avoid console 
  452.    windows smaller than 80X25 or so.
  453.    
  454.    
  455.                         ----- Acknowledgements -----
  456.    Special thanks to John Toebes and the Software Distillery for lots of
  457.    great suggestions, to Jeff White for the handsome icons, and to the many
  458.    contributors who made ongoing development and improvements possible.
  459.    
  460.                               -- Bill Hawes (September 28, 1988)
  461.